\begin{chapter}{Introduction}
\label{chap:introduction}

The 2APL Platform and its corresponding Eclipse plug-in editor were
developed to support the implementation and execution of multi-agent
systems programmed in the 2APL programming
language~\cite{Dastani:08a,D-RULECHP09,CLIMA09}. 2APL (A Practical
Agent Programming Language, pronounced \emph{double-a-p-l}), is a
BDI-based modular agent-oriented programming language that supports
an effective integration of \emph{declarative programming}
constructs such as belief and goals, and \emph{imperative (style)
programming} constructs such as events and plans. The 2APL platform
provides a graphical interface through which a user can load, run,
and monitor the execution of 2APL multi-agent programs using several
tools, such as a state tracer, a log window, and a message monitor,
and allows for different execution modes. The platform allows
communication among agents and can run on several machines connected
in a network. Agents hosted on different 2APL platforms can
communicate with each other. In order to facilitate the
implementation of 2APL multi-agent programs, a 2APL editor plug-in
for Eclipse has been developed. Using this editor it is possible to
load, run, and monitor 2APL multi-agent programs directly from
Eclipse.

In this user guide, we first explain how the 2APL software can be
downloaded, installed, executed, and used. Different tools for
supporting the development of multi-agent programs, such as
monitoring tools, are explained in detail.
Section~\ref{chap:eclipse} presents the details of an Eclipse
plug-in editor that is developed for writing 2APL multi-agent
programs. Section~\ref{chap:language} gives an overview of the
syntax and intuitive meaning of 2APL programming constructs in two
steps. We first explain the main idea of 2APL and present its basic
programming constructs. Then, we explain the idea of modules in 2APL
and present the module related programming constructs. Various
examples are provided to illustrate the use of this programming
language. Finally, section~\ref{chap:environment} explains how
environments can be shared by different agents and how such
environments can be developed and used in the 2APL framework.

\begin{section}{Software requirements}
The 2APL platform has been tested on Windows 2000 and Windows XP, as
well as Mac OS X, Linux and Unix (Solaris). In order to run the 2APL
platform, one needs to have at least Java Runtime Environment (JRE)
6 or Java Developers Kit (JDK) 6 installed on the computer.
\end{section}

\begin{section}{Getting 2APL Software}
In order to use the 2APL Platform and/or its corresponding editor
follow the next steps:
\begin{enumerate}
    \item Go to the 2APL webpage using the following URL:
          $${\tt http://apapl.sourceforge.net/}$$
          and select the {\tt Downloads} option.

    \item There are three download options available. One can download
          only the 2APL platform without the 2APL Eclipse plug-in editor,
          only the 2APL Eclipse plug-in editor without the 2APL platform, or
          the full package consisting of the 2APL platform, the 2APL Eclipse plug-in editor,
          and Eclipse itself.
          \begin{itemize}
                \item The 2APL platform, without its corresponding Eclipse plug-in
                editor, can be downloaded by selecting the option {\tt 2APL
                Platform}. This option allows loading, running, and
                monitoring 2APL multi-agent programs.
                \item The 2APL Eclipse plug-in editor, without the 2APL
                platform, can be downloaded by selecting the option
                {\tt 2APL Eclipse Plug-in Editor}. This editor
                supports writing and editing 2APL multi-agent programs by recognizing and highlighting the 2APL syntax.
                For this option, the Eclipse software should be downloaded from its official website.
                Eclipse can be configured to start the 2APL platform, load a 2APL multi-agent program into
                it, and run the program (see section~\ref{chap:eclipse} for further
                instruction). To run a 2APL multi-agent program, the
                2APL platform (previous item) should be downloaded.
                \item The full integrated package can be downloaded by
                selecting the option {\tt 2APL Full Package: 2APL Platform, Eclipse Plug-in Editor, and
                Eclipse}.
          \end{itemize}
    \item Extract the contents of the downloaded document into a
          directory. In the following, we assume that this directory is
          named {\tt 2APL}.
\end{enumerate}

The downloaded 2APL platform is an archive, called {\tt 2APL.zip},
containing the file {\tt 2apl.jar} and two directories {\tt lib} and
{\tt examples}. The file {\tt 2apl.jar} includes all the class files
of the 2APL Platform, the {\tt lib} directory contains all necessary
files to run the 2APL platform (e.g., the class files of
JIProlog\footnote{JIProlog is a Java based Prolog reasoning engine
that is used by the individual 2APL agents to represent and reason
about their beliefs}), and the {\tt examples} directory contains
some multi-agent systems programmed in 2APL.

The example directory includes a multi-agent system program, called
{\tt harry and sally}. This example is about two agents, {\tt harry}
and {\tt sally}, who are located in the so-called {\tt blockworld}
environment. The {\tt blockworld} environment is a $n \times n$
grid, which can contain agents, bombs, and dustbins in which bombs
can be thrown away. {\tt Sally} is responsible for searching bombs
and notifying Harry when she finds one. {\tt Harry} is responsible
for cleaning up the {\tt blockworld} by picking up the bomb and
throwing it in a dustbin. Chapter \ref{chap:language} will elaborate
on this example in more detail. In the sequel, we will use this
example to explain the 2APL programming language and its platform.
The file {\tt blockworld.jar} is the implementation of the
blockworld environment. The details of the {\tt blockworld}
environment will be explained in chapter \ref{chap:environment}. In
the example directory, there are more examples of 2APL multi-agent
programs. Each example is explained in a readme document that is
included in the directory of the example.
\end{section}

\begin{section}{Getting started}

In this section we will explain how the 2APL platform can be started
and show the basics of loading, running and monitoring the execution
of 2APL MAS-programs. The development of 2APL multi-agent programs
is supported by an editor which is an Eclipse plug-in. This editor
in explained in detailed in section~\ref{chap:eclipse}.

The 2APL platform can be started in:
    \begin{description}
        \item[Windows] by double clicking the file {\tt 2apl.jar}, or
            alternatively, typing {\tt java -jar 2apl.jar} in a command prompt window at
            the {\tt 2APL} directory
        \item[Mac OS] by double clicking the file {\tt 2apl.jar}
        \item[Linux/Unix] by typing {\tt java -jar 2apl.jar} to a
            prompt in the {\tt 2APL} directory
    \end{description}

On every operating system, the 2APL platform can be invoked from the
command prompt. For help the following command can run \texttt{java
-jar 2apl.jar -help}. Here is the output:
\begin{verbatim}
$ java -jar 2apl.jar -help

2APL (A Practical Agent Programming Language) Interpreter

Usage: java -jar 2apl.jar [-nogui] [-nojade] [-help] [<path to MAS file>]

Options:
   -nogui   do not open graphical user interface; start the MAS immediately
   -nojade  skip JADE configuration and run in standalone mode
   -help    print this message
\end{verbatim}

    \begin{figure}
        \begin{center}
            \epsfig{figure=images/configuration.eps,width=.3\textwidth}
            \caption{The window with 2APL configuration options.}\label{fig:configuration}
        \end{center}
    \end{figure}

As illustrated in figure~\ref{fig:configuration}, one needs to
select a configuration option. The first option allows the use of
2APL platform in a stand-alone mode and the last two options start
2APL on top of the Jade~\cite{jade2005} platform. The last two
options are useful when one wants to run a multi-agent program (in a
distributed manner) on different machines. In this user guide, we
focus on the stand-alone run mode of the 2APL platform.

After a successful startup the main user interface (see Fig.~\ref{fig:mainscreen}) appears.
This one allows to load, run, and monitor the
execution of multi-agent systems programmed in 2APL.

    \begin{figure}
        \begin{center}
            \epsfig{figure=images/mainscreen.eps,width=0.8\textwidth}
            \caption{The main 2APL user interface.}\label{fig:mainscreen}
        \end{center}
    \end{figure}

To load an example multi-agent system, one should perform the
following steps:
\begin{enumerate}
    \item Select from the menu {\tt file} $\rightarrow$ {\tt open}, or
    alternatively the {\tt open} button located on the toolbar, and an {\tt
    open file} dialog appears.
    \item Browse to the directory {\tt 2APL}$\backslash${\tt examples}$\backslash${\tt harry and sally} and
    select the file named {\tt harrysally.mas}.
\end{enumerate}

The file with the {\tt .mas} extension specifies the multi-agent
system by indicating which agents should be created, which {\tt
.2apl} files initialize the agents, which environments they can
access and which {\tt .jar} files contain the environments. In this
case, two agents {\tt harry} and {\tt sally} will be created that
act in the {\tt blockworld} environment. The agents are initialized
by {\tt harry.2apl} and {\tt sally.2apl}, respectively. The
environment is implemented by {\tt blockworld.jar}. Note that the
{\tt blockworld} environment is configured by parameters that
determine the size of the grid and the number of robots that will
appear on the grid.

\begin{figure}
    \begin{minipage}{0.6\linewidth}
        \begin{center}
            \epsfig{figure=images/loadedmas.eps,width=\textwidth}
        \end{center}
    \end{minipage}
    \hspace{.5cm}
    \begin{minipage}{0.3\linewidth}
        \begin{center}
            \epsfig{figure=images/blockworld.eps,width=\textwidth}
        \end{center}
    \end{minipage}
    \caption{The main 2APL user interface loaded with {\tt harry and sally} multi-agent program (left), and the {\tt blockworld} user interface (right).}\label{fig:loadedmas}
\end{figure}

After the file has been loaded, the main 2APL user interface as well
as the interface of the {\tt blockworld} appears\footnote{The {\tt
blockworld} environment is implemented as a user interface that
presents a grid. Please note that an environment does not
necessarily generate a user interface.}. These two interfaces are
depicted in figure \ref{fig:loadedmas}. The left panel of the 2APL
user interface allows to toggle between the multi-agent system tab
{\tt Multi-Agent System} and the tabs related to the different
agents located within this multi-agent system (in this case {\tt
harry} and {\tt sally}). The right panel shows different tabs,
depending on whether a specific agent or the multi-agent system has
been selected in the left panel. In case of selecting the
multi-agent system tab {\tt Multi-Agent System}, one can only see
the {\tt Messages} tab in the right panel, showing the messages that
are exchanged between the agents when they are executed.

In case an individual agent has been selected in the left panel, one
can select different tabs in the right panel to observe various
state ingredients of the selected 2APL agent. In this example, and
as illustrated in figure \ref{fig:harry}, the {\tt Overview} tab of
the agent {\tt harry} is selected. This tab enables the user to
observe the mental state (beliefs, goals, and plans) of the agent
{\tt harry}. One can also select the {\tt Belief updates} tab to see
the specification of belief update actions that the agent can
perform, the {\tt PG rules} tab to see the agent's rules that
specify how and by which plans the agent can realise its goals, the
{\tt PC rules} tab to view the agent's rules that specify how the
received events and messages should be handled, the {\tt PR rules}
tab to view the agent's rules that specify how the agent can repair
its failed plans, the {\tt Warnings} tab to see system warnings, the
{State Tracer} tab to monitor the subsequent mental states of the
agent {\tt harry} when it is executed, and the {\tt Log} tab to
observe the agent's execution log. For other examples, the set of
tabs for an individual agent can be different depending on the
programming constructs that are used in the source file of the
agent.

    \begin{figure}
        \begin{center}
            \epsfig{figure=images/harry.eps,width=.7\textwidth}
            \caption{The main 2APL user interface when selecting agent {\tt harry} in the left panel.}\label{fig:harry}
        \end{center}
    \end{figure}

A 2APL program can be executed in different modes by means of the
buttons on the toolbar, which can also be accessed through the {\tt
file} and {\tt run} menu items. The meaning of these buttons is
shown below.

\begin{center}
    \begin{tabular}{c|c}
        \begin{tabular}{cl}
            \epsfig{figure=images/btnopen.eps,width=0.27in,angle=0} & load a {\tt mas} file \\
            \epsfig{figure=images/btnclose.eps,width=0.27in,angle=0} & close {\tt mas} file \\
            \epsfig{figure=images/btnreset.eps,width=0.27in,angle=0} & reload {\tt mas} file \\
        \end{tabular}
        &
        \begin{tabular}{cl}
            \epsfig{figure=images/btnrun.eps,width=0.27in,angle=0} & execute agent(s) in continuous mode \\
            \epsfig{figure=images/btncycle.eps,width=0.27in,angle=0} & execute agent(s) for one deliberation cycle\\
            \epsfig{figure=images/btnstep.eps,width=0.27in,angle=0} & execute agent(s) in step-by-step mode\\
            \epsfig{figure=images/btnpause.eps,width=0.27in,angle=0} & pause execution of agent(s) \\
            \epsfig{figure=images/btnall.eps,width=0.27in,angle=0} & apply abovementioned operations to all agents\\
            \epsfig{figure=images/btnsingle.eps,width=0.27in,angle=0} & apply abovementioned operations to the
            selected agent\\
            \\
            \epsfig{figure=images/btnmessageagent.eps,width=0.27in,angle=0} & send a
            message to an agent.
        \end{tabular}
    \end{tabular}
\end{center}

Alternatively, one may load and start the multi-agent system
directly from the command line. One can also start the interpreter
without a graphic user interface. To see the help on the available
options execute \texttt{java -jar 2apl.jar -help} in the command
line prompt.
\end{section}



\begin{section}{Execution Monitoring Tools}

In this section we present the tools that can be used in the 2APL
platform to monitor the execution of individual agents. There are
three monitoring tools: {\tt Auto-update Overview}, {\tt State
Tracer}, and {\tt Log}. These tools, which can be accessed through
the {\tt Debug} toolbar button of the 2APL platform, are activated
by default. The tools can be deactivated to improve the execution
performance of the 2APL platform. The activation of the tools
generates specific information and presents them in the
corresponding tabs. The tabs can be used in the right panel of the
2APL main user interface when an individual agent is selected in the
left panel of the user interface.

The {\tt Overview} tab consists of three panels called {\tt
Beliefbase}, {\tt Goalbase}, and {\tt Planbase}. When this tab is
active, the beliefs, goals, and plans of the current state of the
selected agent are presented in the {\tt Beliefbase}, {\tt
Goalbase}, and {\tt Planbase} panels, respectively. Figure
\ref{fig:harry} illustrates the use of the {\tt Overview} tab which
presents the beliefs, goals, and plans of agent {\tt harry} from its
initial state directly after loading the multi-agent program.
Executing the multi-agent program will present updated information
about the agent {\tt harry}.

The {\tt State Tracer} tab is a temporal version of the {\tt
Overview} tab and stores the beliefs, goals, and plans of all agents
during execution. Because an execution generates a trace of agents'
states (beliefs, goals, and plans), the tools and its corresponding
tab are called state tracer. This tool allows a user to execute a
multi-agent program for a while, pause the execution, and browse
through the execution of each agent. With the buttons in the upper
part of the tab one can navigate through the state trace. The user
can select how many states (one, two, or three) to show on one
screen and whether to show the beliefs, plans, goals, and log with
the menu on the lower part of the tab. Figure~\ref{fig:statetracer}
illustrates the use of the state trace tool for monitoring the
execution of the {\tt harry} agent. This tab shows the execution of
the multi-agent program at states 8, 9, and 10. It also shows that
{\tt harry} has performed action {\tt
@blockworld(associateWith(robot0),\_,0)} in state 8 of the
execution.

\begin{figure}
    \begin{center}
        \epsfig{figure=images/statetracer.eps,width=.7\textwidth}
        \caption{The {\tt State Traces} tab shows the execution trace of agent {\tt harry}.}\label{fig:statetracer}
    \end{center}
\end{figure}

Finally, the {\tt Log} tool presents information about the
deliberation steps of individual agents. As illustrated in
Figure~\ref{fig:log}, the {\tt Log} tab indicates whether {\tt
harry} has executed an action, processed an internal event, a
message, or an external event. The user can browse through this
window to see which deliberation steps have been preformed.

\begin{figure}
    \begin{center}
        \epsfig{figure=images/log.eps,width=.6\textwidth}
        \caption{The {\tt Log} tab presents information about deliberation steps of agent {\tt harry}.}\label{fig:log}
    \end{center}
\end{figure}

\end{section}
\end{chapter}
